The Ocean Health Index works primarily with freely available, open-source software. To work the the Toolbox, there are several software programs you will need to download.
Download R from cran.r-project.org and follow the install instructions for your computer.
If you already have R installed, check cran.r-project.org for updates. There are frequent updates available, and the current version is identified on the website. Compare what is available with what you already have on your computer by typing sessionInfo() into your R console (see also: learning R).
We highly recommend working with RStudio, which is an interface that makes working with R much easier. RStudio also has great compatibility with GitHub, which we recommend for conducting regional assessments so you can collaborate with your team easily. RStudio does not get updated as often as R does, but check for updates regularly.
Rmarkdown is a powerful way to track progress as you use the Toolbox to reflect the characteristics and priorities in your study region. Here are some Rmarkdown tips.
The Ocean Health Index (OHI) Toolbox is written in R and uses GitHub, an open-source development platform to develop and share software and data. GitHub has powerful versioning capabilities, which allow changes to be archived and tracked by each user. This is incredibly useful to not only document what work has been done, but how it differs from work done in the past, and who is responsible for the changes. GitHub enables easy collaboration with others, including the OHI team.
OHI has several repositories (‘repos’) where data and code are stored. From the GitHub glossary:
A repository is the most basic element of GitHub. They’re easiest to imagine as a project’s folder. A repository contains all of the project files (including documentation), and stores each file’s revision history. Repositories can have multiple collaborators and can be either public or private.
OHI-Science is the ‘owner’ of OHI repositories, and individual users contribute to these repositories when they have permission. This simple example illustrates GitHub’s collaborative workflow with the ohi-israel repo owned by OHI-Science:
We recommend that groups interested in conducting OHI assessments do so through GitHub. This will enable collaboration and transparency, and will provide access to the latest developments in the Toolbox software. To get started, follow the steps below. The OHI team will create a repository for your regional assessment.
It is also possible to conduct a regional assessment without GitHub. We do not recommend this because it is more difficult for you to track progress and decisions, and for us to help or advise you. However, if this is preferable, see the instructions here. We can always get your filesystem onto GitHub later.
![alt text(./fig/overview_requirements.png)
Make sure you have the most current version of R and RStudio.
To get started, signup for a GitHub account, and provide your username to bbest@nceas.ucsb.edu or lowndes@nceas.ucsb.edu so you can access your ohi-[assessment] repository.
git is required to work behind the scenes on your computer. Download and install git. (Here are a few tips).
You will then need to set up your Git Identity, which identifies you with any changes made. You will use the command line:
Substitute your GitHub user information with the user John Doe:
git config --global user.name jdoe
and then:
git config --global user.email johndoe@example.com
You can check settings with the following:
git config --list
Quit the Terminal after typing:
exit
Contact the OHI team (bbest@nceas.ucsb.edu or lowndes@nceas.ucsb.edu) to create a repository for your group. The repository will be stored on github.com and called OHI-Science/ohi-[assessment]: for example, github.com/OHI-Science/ohi-israel.
Once there is a repository for your OHI regional assessment called OHI-Science/ohi-[assessment], you can decide whether you will clone and work directly from that repository or from a forked repository. There are benefits to both approaches:
OHI-Science/ohi-[assessment] (see Cloning options) and push/pull from there.ohi-science/ohi-[assessment] while your collaborators do the same. This is a good way for someone who is not in the core team of the assessment to contribute comments.** With either approach, we recommend creating a folder called github in your root directory so that you can clone the repository to this file path: ~/github/ohi-[assessment]. This will make collaborating much simpler since everyone will work with the same file path.
There are several options to clone the ohi-[assessment] repository to your local machine:
Clone in Desktop button from the online repository (see the Getting started guide on a Mac and Windows)All of the files available from the online server repository https://github.com/OHI-Science/ohi-[assessment] are now cloned on your local computer, in the location you specified (we recommend cloning the repository to this file path: ~/github/ohi-[assessment]).
You will work on your computer to change the files in ~/github/ohi-[assessment] to reflect the desired modifications your team has identified for your regional assessment. All changes within this folder will be tracked by GitHub when you commit these changes, even if you make these changes outside of R or RStudio. This means that you can delete or paste files in the Mac Finder or Windows Explorer, edit layers.csv and goals.csv in Excel or a text editor, and modify functions.r in RStudio, and commit all these changes to GitHub to track the changes you make.
Committing and pushing changes can be done using RStudio or the Github App
Launch your ohi-[assessment] project in RStudio by double-clicking the ohi-[assessment].Rproj file. From RStudio, Commit locally, associating a message with each set of changes.
When you modify or add a file, the file will appear in the ‘Git’ window. In the example below, the file test.R was created.
github.com/OHI-Science/ohi-[assessment]. Your changes are now visable online.The Github App can also be used to commit and sync any changes made locally in the github folder. To do so, write a summary and description in the respective message bars in the Github App window, then click on commit and sync.
![alt text(./fig/github_app.png)
Always pull before pushing commits.
It is possible to conduct a regional assessment without having a GitHub account. You can do a one-time download from the GitHub repository and then work locally on your computer without syncing to the GitHub server. We do not recommend this because it is more difficult for you to track progress and decisions, and for us to help or advise you. We recommend accessing a repository with GitHub but provide instructions here of how to access a repository without Github. We can always get your filesystem onto GitHub later.
Download R and install this on your computer. If you already have R installed, check the website for updates. There are frequent updates to the R software, and the current version is identified on the websited. Compare what is available from their wesite with what you already have on your computer by typing sessionInfo() into your R console. (This will also identify packages you have installed).
While not required, we highly recommend working with RStudio, which is an interface that makes working with R much easier. RStudio also has great compatibility with GitHub so you can collaborate with your team directly from your R code. RStudio does not get updated as often as R does, but it is good to check for updates regularly.
Contact the OHI team (bbest@nceas.ucsb.edu or lowndes@nceas.ucsb.edu) to create a repository for your group. The repository will be stored on github.com and called OHI-Science/ohi-[assessment]: for example, github.com/OHI-Science/ohi-israel.
When your repository has been created, enter the url in to an internet browser (for example, github.com/OHI-Science/ohi-israel). Click Download ZIP.
Unzip the downloaded folder ohi-[assessment]-master and save the folder on your computer. We recommend creating a folder called github in your root directory and saving your repository to this file path: ~/github/ohi-[assessment]. This will make collaborating much simpler since everyone will work with the same file path.
Double-click ohi-[assessment]/ohi-[assessment].Rproj: this will launch RStudio. Be sure to have the latest version of R and RStudio.
Open ohi-[assessment]/[scenario]/launch_app_code.R (for example, ohi-israel/med2014/launch_app_code.R). You can open this from within RStudio: >
Launch the Toolbox user interface Run launch_app_code.R to launch the Toolbox user interface. Notice that when the user interface opens, it may not be able to display Output Scores. This is because they have not been calculated yet: select Input Layer instead to see the map: >
Navigate through the Toolbox file system Become familiar with the Toolbox file system. **Note: this page is under active development**
To change data presented: Within the folder ohi-[assessment]/[scenario]layers, open a .csv file and see that there are fewer regions represented than in the global layers folder.
This is because we have modified all the files to coincide with the six regions in the ohi-israel assessment. All these files have the suffix _global2013.csv because they are just copies of the global assessment, with the same value copied into each regions. For example: alien_species_global2013.csv has six region identifiers (rgn_ids, consistent with ohi-israel’s six regions.
At this point, only one file is specific to the assessment: **ohi-[assessment]/[scenario]/layers/rgn_labels_[scenario].csv**, which is the file that describes all the regions (in this example, in Hebrew):
For the data layers that you will update, we suggest you replace the _global2013.csv file, with a file that has a suffix identifying your scenario. So alien_species_global2013.csv would become alien_species_med2014.csv or alien_species_israel2014.csv. You can keep a copy of the old *_global2013.csv* file in a separate foler or delete it (there is a record of it on the GitHub website (example).
ohi-[assessment]/[scenario]/layers.csv is a registry (directory) of where the Toolbox looks for the data it uses. When you change a filename to *_china2014.csv*, you will need to update the registry so the ‘filename’ column so the Toolbox know where to look.While you’ve been working on your forked repository locally on your computer (ex: remi-daigle/ohi-global), there may be committed updates in the owner’s repository that is ‘upstream’ (ex: OHI-Science/ohi-global). To ensure that you are working with the most updated repository, you need to update your fork by creating a pull request. See some tips on process here.
To do this on the command line, see help.github.com.
To do this through Github:
OHI-Science and the repo is ohi-global. Note that there are recent updates by user Melsteroni. To pull the most recent version of ohi-global from OHI-Science, click on the green button.remi-daigle\ohi-global. The head fork is the owner’s repo: OHI-Science\ohi-global. You can see those most recent commits by Melsteroni. Now you can click ‘Create pull request’.Note:
when the base fork and head fork are identified, we are in the forked repo `remi-daigle/ohi-global’. It is also possible to create a pull request the the head fork from this location.
if that if you get an error There isn’t anything to compare, make sure you are still comparing forks, not branches.
Rmarkdown is a simple formatting tool for creating HTML, PDF, presentations, and Microsoft Word documents, and it can render R code within those formats. See this great post as an introduction to its capabilities.
Here are a few examples of documents written in Rmarkdown, rendered in .html and .pdf formats. Also, to see how Rmarkdown files can render code, look at the comparison of three OHI scenario goals.csv files in its raw .rmd format and rendered .md format.
With the Ocean Health Index, we use Rmarkdown documents together with GitHub. To create or edit Rmarkdown content, you can do so with R and RStudio, or directly online on the GitHub interface.
With an GitHub account and the correct permissions, you can provide edits to files within github.com. This will actually create a copy of the file (that GitHub calls a ‘fork’) that you can edit and then suggest changes to the owner of the file.
Because GitHub cannot render .Rmd files, editing those files directly is difficult because you cannot immediately see your suggested edits. You are able to see rendered edits you make to .md files, but this will cause a problem because the next time the .Rmd file is rendered, it will overwrite the edits to .md. The temporary solution is to make edits to the .md file, so you can see the rendered changes, propose the file change, and then look at the changes side-by-side while you make those same changes to the .Rmd file.
Select the most recent change:
Make edits side-by-side:
Your edits will be reviewed and merged into the documents by the file owner.
To get started writing in Rmarkdown, first, update R and RStudio.
Then, in RStudio, install Rmarkdown (which also installs the required pandoc) with the pull-down menu or by pasting this into the console:
install.packages('rmarkdown')
Then, open a new .Rmd document. Instead of a blank document, it will give a template that you can Knit to see how it renders. Try it.
To add your own content, follow instructions about syntax. When you click the Knit button, a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. Rendering the .Rmd as both .html and .md documents is a good way to go. The .html file will show the rendered content, and is a good way to test that your syntax is correct. The .md file needs something something more to render its format–something that GitHub can provide. So when the md file is on GitHub, it will be very easy to read. If you’re reading this tutorial on GitHub, you’re reading the .md file.
Assign the output in the following way (spacing matters). Note that there are additional options you can specify (see the Formats tab of the Rmarkdown page for more details.
---
title: "Rmarkdown output formats"
output:
html_document:
fig_caption: yes
keep_md: yes
number_sections: no
toc: yes
md_document:
variant: markdown_github
---
Rmarkdown is a powerful tool that can create publication-worthy documents, and has a lot of built-in options. However, like any new language or software, it takes a bit of time to learn how to use it. If there is something you are trying to do, Google your problem because it is likely that someone else has had the same question, and that someone else has had the answer. For example, here are a few solutions to problems you may have:
The Toolbox prints messages during its processing to help guide error checking and debugging. Here are a few troubleshooting tips.
(** note: this page is under development).
When you restart your R Session (Session > Restart R on a Mac), if you see that it is trying to load ohicore, it may give you an error:
You do not want it to load ohicore or to save anything in your workspace. You will need to change the default setting from you .Rproj file. Steps to do this:
Example:
Running Setup()...
Calculating Pressures...
The following components for NP are not in the aggregation layer np_harvest_product_weight categories (fish_oil, ornamentals, seaweeds): corals, shells, sponges
Error in data.frame(names(P), P) :
arguments imply differing number of rows: 0, 1
This error means you should update your pressures matrix because it expects there to be components that your region does not have.
Example: >
This error means there is an empty column in pressures_matrix.csv, and the Toolbox cannot handle empty columns.
This error means you should check that there is at least one entry for each goal (for each row) in resilience_matrix.csv.